Add collection/franchise ingestion

Collections were bare stubs (name only) lazily created the moment a
movie's belongs_to_collection reference was seen. Adds a real
ingest_collection pipeline: TMDb's /collection/{id} for overview and
poster/backdrop artwork, plus ordered CollectionMovie membership --
linking only movies already ingested into Aurora, the same
never-fabricate-a-stub rule movie recommendations already follow.

get_or_create_collection now refreshes name/overview on an existing
stub instead of only creating, guarded so a bare movie-stub call
(overview=None) never clobbers real data a full ingestion already
filled in.

New POST /api/v1/admin/ingest/collection endpoint and
ingest_collection_task; GET /api/v1/collections/{id} needed no changes
since its read path (collection_service.py) already assembled the full
detail shape.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

docs/api.md

@@ -127,6 +127,12 @@ network and a production company are both `Company` rows distinguished by
 | GET | `/api/v1/collections/{aurora_id}` |
 | GET | `/api/v1/companies/{aurora_id}` |
 
+Collection detail's `movies` list only includes movies already ingested
+into Aurora — `POST /api/v1/admin/ingest/collection` links a franchise's
+member movies purely by external-id lookup, the same never-fabricate-a-stub
+rule `recommendations` follows, so a franchise fills in as more of its
+movies get ingested rather than all at once.
+
 ## Administrative (section 17: "separately protected")
 
 Require header `X-API-Key: <one of AURORA_ADMIN_API_KEYS>`. Never exposed to
@@ -139,6 +145,7 @@ you want network-level isolation too.
 | POST | `/api/v1/admin/ingest/person` | `{"tmdb_id": "6384"}` | Same, for a person profile. |
 | POST | `/api/v1/admin/ingest/series` | `{"tmdb_id": "1396", "include_seasons": false}` | Ingests the series and season *stubs* (number, title, air date, poster) — no episodes yet. With `include_seasons: true`, also enqueues an `ingest/season` job for every season once the series finishes (opt-in: some shows have dozens of seasons, each a separate TMDb call). |
 | POST | `/api/v1/admin/ingest/season` | `{"tmdb_id": "1396", "season_number": 1}` | Ingests one season's full episode list. Requires the series to already be ingested (`ingest/series` first) — fails with a clear error otherwise. |
+| POST | `/api/v1/admin/ingest/collection` | `{"tmdb_id": "2344"}` | Ingests a franchise's own metadata (overview, poster/backdrop) and links its already-ingested member movies (see "Collections / Companies" above). Movie ingestion also lazily creates a bare name-only stub the first time it sees a `belongs_to_collection` reference — this is what actually fills it in. |
 | GET | `/api/v1/admin/ingest/jobs/{job_id}` | — | Poll job status: `pending` → `running` → `succeeded`/`failed`/`retrying`. |
 
 ## Errors

docs/database.md

@@ -60,7 +60,14 @@ and a movie studio have the same shape (name, logo, country, parent
 company), so a separate `Network` entity would just duplicate columns.
 `collections` (franchises) are first-class, with their own artwork and
 `collection_relations` for shared-universe links between collections
-(section 9).
+(section 9). A collection starts as a bare name-only stub the first time
+movie ingestion sees a `belongs_to_collection` reference; its real overview,
+poster/backdrop, and ordered `collection_movies` membership are filled in by
+`app/services/ingestion/collection_ingestion.py:ingest_collection`
+(`POST /api/v1/admin/ingest/collection`), which — like recommendations —
+only links movies Aurora has already ingested rather than fabricating stubs
+for the rest of the franchise. `collection_relations` and `collection_series`
+exist in the schema for future use but nothing populates them yet.
 
 ## Artwork / Videos