[Codex] Add JSDoc and file-level comments to all remaining source files

[saggacce]

Context

A documentation pass has been started in branch `docs/codebase-documentation` (merged partially). The following files have already been documented:

• `workers/data-sync/prisma/schema.prisma` ✅
• `apps/api/src/services/match-service.ts` ✅
• `apps/api/src/middleware/*.ts` (all 5 files) ✅
• `workers/data-sync/src/client.ts` ✅

What needs to be done

Add JSDoc and inline comments to all remaining files so a new developer can understand purpose, parameters, return values and non-obvious logic.

Standards to follow

File-level comment (top of every file):
```ts
/**

• @fileoverview One-sentence description of the file's responsibility.
• More detail if needed — what it does, what calls it, what it calls.
  */
  ```

Function JSDoc (all exported functions):
```ts
/**

• Description of what the function does.
• @PARAM paramName - What it is
• @returns What it returns
• @throws {AppError} When and why
  */
  ```

Interface/type JSDoc: one-line description above each field that isn't self-explanatory.

Inline comments: only for non-obvious logic — WHY not WHAT.

Do NOT add comments that just restate the code. No multi-line comment blocks on simple functions.

Files to document (grouped by priority)

Priority 1 — Services (most read by new devs)

• `apps/api/src/services/sync-service.ts` (1581 lines — focus on exported functions and the two-phase sync architecture)
• `apps/api/src/services/player-service.ts`
• `apps/api/src/services/team-service.ts` (complex aggregations)
• `apps/api/src/services/analyst-service.ts` (LLM pipeline)
• `apps/api/src/services/review-service.ts`
• `apps/api/src/services/config-service.ts`
• `apps/api/src/services/hero-meta-service.ts`
• `apps/api/src/services/report-service.ts`
• `apps/api/src/services/llm-service.ts`
• `apps/api/src/services/tier-access.ts`

Priority 2 — Routes

• `apps/api/src/routes/teams.ts`
• `apps/api/src/routes/players.ts`
• `apps/api/src/routes/matches.ts`
• `apps/api/src/routes/auth.ts`
• `apps/api/src/routes/internal-auth.ts`
• `apps/api/src/routes/review.ts`
• `apps/api/src/routes/vod.ts`
• `apps/api/src/routes/reports.ts`
• `apps/api/src/routes/analyst.ts`
• `apps/api/src/routes/invitations.ts`
• `apps/api/src/routes/profile.ts`
• `apps/api/src/routes/feedback.ts`
• `apps/api/src/routes/hero-meta.ts`
• `apps/api/src/routes/sync.ts`
• `apps/api/src/routes/patches.ts`
• `apps/api/src/routes/map-zones.ts`

Priority 3 — Frontend hooks and context

• `apps/web/src/hooks/useAuth.ts`
• `apps/web/src/hooks/useConfig.ts`
• `apps/web/src/contexts/PermissionsContext.tsx` (once PR feat: platform permissions system — fine-grained role access control #184 is merged)
• `apps/web/src/api/client.ts` (file-level overview + JSDoc on helper functions)

Priority 4 — Frontend components

• `apps/web/src/components/FeedbackButton.tsx`
• `apps/web/src/components/HeroAvatar.tsx`
• `apps/web/src/components/LinkPlayerModal.tsx`
• `apps/web/src/components/RankIcon.tsx`

Priority 5 — Frontend pages (file-level comment + key component JSDoc only)

All 22 pages in `apps/web/src/pages/`. For large pages (MatchDetail, TeamAnalysis, PlayerScouting) document the main component and any complex helper functions.

Priority 6 — Worker

• `workers/data-sync/src/index.ts`
• `workers/data-sync/src/sync/players.ts`
• `workers/data-sync/src/sync/matches.ts`
• `workers/data-sync/src/sync/versions.ts`

Branch

Work in `docs/codebase-documentation` and push there. PR target: `develop`.

Acceptance criteria

• Every file has a `@fileoverview` file-level comment
• All exported functions have JSDoc with at minimum a one-line description
• Complex logic (aggregations, sync pipelines, auth flows) has inline WHY comments
• No comments that just repeat what the code says
• TypeScript compiles clean (`npx tsc --noEmit`) on both `apps/api` and `apps/web`