Phase 6: Update database layer identifier documentation

- Updated AnimeSeries model docstring to clarify key is primary identifier
- Updated folder field to indicate metadata-only usage
- Updated AnimeSeriesService docstring and get_by_key method
- Updated infrastructure.md with database identifier documentation
- All 996 tests passing

src/server/database/models.py

@@ -38,20 +38,31 @@ class AnimeSeries(Base, TimestampMixin):
     Represents an anime series with metadata, provider information,
     and links to episodes. Corresponds to the core Serie class.
     
+    Series Identifier Convention:
+        - `key`: PRIMARY IDENTIFIER - Unique, provider-assigned, URL-safe
+          (e.g., "attack-on-titan"). Used for all lookups and operations.
+        - `folder`: METADATA ONLY - Filesystem folder name for display
+          (e.g., "Attack on Titan (2013)"). Never used for identification.
+        - `id`: Internal database primary key for relationships.
+    
     Attributes:
-        id: Primary key
-        key: Unique identifier used by provider
-        name: Series name
+        id: Database primary key (internal use for relationships)
+        key: Unique provider key - PRIMARY IDENTIFIER for all lookups
+        name: Display name of the series
         site: Provider site URL
-        folder: Local filesystem path
+        folder: Filesystem folder name (metadata only, not for lookups)
         description: Optional series description
         status: Current status (ongoing, completed, etc.)
         total_episodes: Total number of episodes
         cover_url: URL to series cover image
-        episodes: Relationship to Episode models
-        download_items: Relationship to DownloadQueueItem models
+        episodes: Relationship to Episode models (via id foreign key)
+        download_items: Relationship to DownloadQueueItem models (via id foreign key)
         created_at: Creation timestamp (from TimestampMixin)
         updated_at: Last update timestamp (from TimestampMixin)
+    
+    Note:
+        All database relationships use `id` (primary key), not `key` or `folder`.
+        Use `get_by_key()` in AnimeSeriesService for lookups.
     """
     __tablename__ = "anime_series"
     
@@ -63,7 +74,7 @@ class AnimeSeries(Base, TimestampMixin):
     # Core identification
     key: Mapped[str] = mapped_column(
         String(255), unique=True, nullable=False, index=True,
-        doc="Unique provider key"
+        doc="Unique provider key - PRIMARY IDENTIFIER for all lookups"
     )
     name: Mapped[str] = mapped_column(
         String(500), nullable=False, index=True,
@@ -75,7 +86,7 @@ class AnimeSeries(Base, TimestampMixin):
     )
     folder: Mapped[str] = mapped_column(
         String(1000), nullable=False,
-        doc="Local filesystem path"
+        doc="Filesystem folder name - METADATA ONLY, not for lookups"
     )
     
     # Metadata

src/server/database/service.py

@@ -43,6 +43,11 @@ class AnimeSeriesService:
     
     Provides methods for creating, reading, updating, and deleting anime series
     with support for both async and sync database sessions.
+    
+    Series Identifier Convention:
+        - Use `get_by_key()` for lookups by provider key (primary identifier)
+        - Use `get_by_id()` for lookups by database primary key (internal)
+        - Never use `folder` for identification - it's metadata only
     """
     
     @staticmethod
@@ -115,12 +120,19 @@ class AnimeSeriesService:
     async def get_by_key(db: AsyncSession, key: str) -> Optional[AnimeSeries]:
         """Get anime series by provider key.
         
+        This is the PRIMARY lookup method for series identification.
+        Use this method instead of get_by_id() when looking up by
+        the provider-assigned unique key.
+        
         Args:
             db: Database session
-            key: Unique provider key
+            key: Unique provider key (e.g., "attack-on-titan")
         
         Returns:
             AnimeSeries instance or None if not found
+        
+        Note:
+            Do NOT use folder for lookups - it's metadata only.
         """
         result = await db.execute(
             select(AnimeSeries).where(AnimeSeries.key == key)