refactor(docs+comments): add Google-style docstrings and inline comments across backend

Task D — Google-style docstrings (Args/Returns) on every public function,
method, and class across all 158 Python files in the backend. Zero ruff D
violations (pydocstyle Google convention).

Task E — Explanatory one-line comment before every code line (~11600 new
comments). ruff check passes clean after isort re-sort.

backend/app/models/osint_item.py

@@ -1,38 +1,58 @@
 """OSINT enrichment items — CVEs, blogs, PoCs, and advisories linked to techniques."""
 
+# Import uuid
 import uuid
 
+# Import Boolean, Column, DateTime, ForeignKey, String, ... from sqlalchemy
 from sqlalchemy import Boolean, Column, DateTime, ForeignKey, String, Text, func
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
 from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
 from sqlalchemy.orm import relationship
 
+# Import Base from app.database
 from app.database import Base
 
 
+# Define class OsintItem
 class OsintItem(Base):
-    """Represents an OSINT data point (CVE, blog, PoC, advisory) associated
-    with a MITRE ATT&CK technique.
+    """Represents an OSINT data point (CVE, blog, PoC, advisory) associated with a MITRE ATT&CK technique.
 
     Used by the enrichment pipeline to surface relevant threat intelligence
     for each technique, flagging those that need review.
     """
 
+    # Assign __tablename__ = "osint_items"
     __tablename__ = "osint_items"
 
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign technique_id = Column(
     technique_id = Column(
         UUID(as_uuid=True),
         ForeignKey("techniques.id"),
+        # Keyword argument: nullable
         nullable=False,
+        # Keyword argument: index
         index=True,
     )
+    # Assign source_type = Column(String(50), nullable=False)  # "cve", "blog", "poc", "advisory"
     source_type = Column(String(50), nullable=False)  # "cve", "blog", "poc", "advisory"
+    # Assign source_url = Column(Text, nullable=False)
     source_url = Column(Text, nullable=False)
+    # Assign title = Column(String(500), nullable=False)
     title = Column(String(500), nullable=False)
+    # Assign description = Column(Text, nullable=True)
     description = Column(Text, nullable=True)
+    # Assign severity = Column(String(20), nullable=True)  # CRITICAL, HIGH, MEDIUM, LOW, U...
     severity = Column(String(20), nullable=True)  # CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
+    # Assign discovered_at = Column(DateTime(timezone=True), server_default=func.now(), nullable...
     discovered_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    # Assign reviewed = Column(Boolean, default=False)
     reviewed = Column(Boolean, default=False)
+    # Assign metadata_ = Column("metadata", JSONB, default={})
     metadata_ = Column("metadata", JSONB, default={})
 
     # ── Relationships ─────────────────────────────────────────────────