chore: improve documentation and fix Team name typos

- Clarify database workflow in copilot-instructions.md with detailed
  explanation of migration process and three use cases
- Update Data/ folder description in README.md structure diagram
- Add XML documentation comments for PlayerData methods
- Fix team name typos
- Add log function documentation in run-migrations script

Author: nanotaboada

.github/copilot-instructions.md

@@ -294,11 +294,26 @@ dotnet ef database update --project src/Dotnet.Samples.AspNetCore.WebApi
 ./scripts/run-migrations-and-copy-database.sh
 ```
 
-**Important**: The `run-migrations-and-copy-database.sh` script:
-- Resets the placeholder database file
-- Runs all migrations
-- Copies the generated database from `bin/Debug/net8.0/storage/` to `storage/`
-- Requires `dotnet ef` CLI tool installed globally
+**Database Workflow Explained:**
+
+The project maintains a **pre-seeded database** at `storage/players-sqlite3.db` to support three use cases:
+1. **Clone & Run** - Developers can clone the repo and run immediately without manual DB setup
+2. **Recreate from Scratch** - Use the script to rebuild the database with all migrations
+3. **Docker** - Container gets a copy of the pre-seeded database on first startup
+
+**How `run-migrations-and-copy-database.sh` works:**
+1. **Creates empty file** at `storage/players-sqlite3.db` (version-controlled source location)
+2. **Runs migrations** via `dotnet ef database update`
+   - EF Core uses `AppContext.BaseDirectory/storage/players-sqlite3.db`
+   - During migration, `AppContext.BaseDirectory` = `bin/Debug/net8.0/`
+   - EF Core creates/updates database at `bin/Debug/net8.0/storage/players-sqlite3.db`
+   - Applies all migrations: creates schema, seeds 26 players (11 starting + 15 substitutes)
+3. **Copies migration-applied database** from `bin/Debug/net8.0/storage/` back to `storage/`
+   - Updates the version-controlled database with latest schema + seed data
+   - This file is included in git and copied to build output via `.csproj` configuration
+
+**Requirements:**
+- `dotnet ef` CLI tool installed globally (`dotnet tool install --global dotnet-ef`)
 
 ### Docker Operations
 ```bash

README.md

@@ -75,7 +75,7 @@ src/Dotnet.Samples.AspNetCore.WebApi/
 │   ├── Player.cs
 │   ├── PlayerRequestModel.cs
 │   └── PlayerResponseModel.cs
-├── Data/                       # EF Core DbContext
+├── Data/                       # EF Core DbContext and migrations
 │   └── PlayerDbContext.cs
 ├── Mappings/                   # AutoMapper profiles
 │   └── PlayerMappingProfile.cs

scripts/run-migrations-and-copy-database.sh

@@ -8,6 +8,8 @@ PROJECT_BASE_PATH="$PROJECT_ROOT_PATH/bin/Debug/net8.0"
 SOURCE_FILE_PATH="$PROJECT_BASE_PATH/storage/$DATA_FILE"
 TARGET_FILE_PATH="$PROJECT_ROOT_PATH/storage/$DATA_FILE"
 
+# log prints a formatted log message prefixed by an emoji and timestamp, followed by the log level and message.
+# Parameters: emoji — emoji or symbol to prefix the entry; level — severity or level label; message — the log text.
 log() {
     local emoji=$1
     local level=$2
@@ -60,4 +62,4 @@ if [ -f "$TARGET_FILE_PATH" ]; then
 else
     log "⚠️" "WARNING" "Something went wrong. The destination file was not found."
     exit 1
-fi
+fi

src/Dotnet.Samples.AspNetCore.WebApi/Utilities/PlayerData.cs

@@ -1,4 +1,4 @@
-using System.Text.Json;
+using System.Text.Json;
 using Dotnet.Samples.AspNetCore.WebApi.Enums;
 using Dotnet.Samples.AspNetCore.WebApi.Models;
 
@@ -153,6 +153,10 @@ public static List<Player> MakeStarting11()
         ];
     }
 
+    /// <summary>
+    /// Create a predefined starting eleven of players where each player has a fixed GUID identifier and full profile data.
+    /// </summary>
+    /// <returns>A list of 11 Player instances representing the starting lineup; each entry includes a predefined Id (Guid) and populated fields such as name, date of birth, squad number, position (and abbreviation), team, league, and Starting11 set to true.</returns>
     public static List<Player> MakeStarting11WithId()
     {
         return
@@ -311,6 +315,10 @@ public static List<Player> MakeStarting11WithId()
         ];
     }
 
+    /// <summary>
+    /// Create a predefined list of 15 substitute players with full profile data but without Id values.
+    /// </summary>
+    /// <returns>A list of 15 Player instances representing substitute players; each entry includes populated fields such as name, date of birth, squad number, position (and abbreviation), team, league, and Starting11 set to false. Id values are not assigned.</returns>
     public static List<Player> GetSubstitutes()
     {
         return
@@ -349,7 +357,7 @@ public static List<Player> GetSubstitutes()
                 SquadNumber = 2,
                 Position = Position.RightBack.Text,
                 AbbrPosition = Position.RightBack.Abbr,
-                Team = "Villareal",
+                Team = "Villarreal",
                 League = "La Liga",
                 Starting11 = false,
             },
@@ -362,7 +370,7 @@ public static List<Player> GetSubstitutes()
                 SquadNumber = 4,
                 Position = Position.RightBack.Text,
                 AbbrPosition = Position.RightBack.Abbr,
-                Team = "Nottingham Forrest",
+                Team = "Nottingham Forest",
                 League = "Premier League",
                 Starting11 = false,
             },
@@ -510,6 +518,10 @@ public static List<Player> GetSubstitutes()
         ];
     }
 
+    /// <summary>
+    /// Create a predefined list of 15 substitute players where each player has a fixed GUID identifier and full profile data.
+    /// </summary>
+    /// <returns>A list of 15 Player instances representing substitute players; each entry includes a predefined Id (Guid) and populated fields such as name, date of birth, squad number, position (and abbreviation), team, league, and Starting11 set to false.</returns>
     public static List<Player> GetSubstitutesWithId()
     {
         return
@@ -551,7 +563,7 @@ public static List<Player> GetSubstitutesWithId()
                 SquadNumber = 2,
                 Position = Position.RightBack.Text,
                 AbbrPosition = Position.RightBack.Abbr,
-                Team = "Villareal",
+                Team = "Villarreal",
                 League = "La Liga",
                 Starting11 = false,
             },
@@ -565,7 +577,7 @@ public static List<Player> GetSubstitutesWithId()
                 SquadNumber = 4,
                 Position = Position.RightBack.Text,
                 AbbrPosition = Position.RightBack.Abbr,
-                Team = "Nottingham Forrest",
+                Team = "Nottingham Forest",
                 League = "Premier League",
                 Starting11 = false,
             },