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/user.py

@@ -1,14 +1,21 @@
+"""SQLAlchemy model for the users table."""
+
+# Import uuid
 import uuid
 
+# Import Boolean, Column, DateTime, String, func from sqlalchemy
 from sqlalchemy import Boolean, Column, DateTime, String, func
+
+# Import UUID from sqlalchemy.dialects.postgresql
 from sqlalchemy.dialects.postgresql import UUID
 
+# Import Base from app.database
 from app.database import Base
 
 
+# Define class User
 class User(Base):
-    """
-    User model for authentication and authorization.
+    """User model for authentication and authorization.
 
     Possible roles:
     - admin: Full system access
@@ -18,14 +25,24 @@ class User(Base):
     - blue_lead: Blue team lead - can validate tests
     - viewer: Read-only access (default)
     """
+    # Assign __tablename__ = "users"
     __tablename__ = "users"
 
+    # 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 username = Column(String, unique=True, nullable=False)
     username = Column(String, unique=True, nullable=False)
+    # Assign email = Column(String, nullable=True)
     email = Column(String, nullable=True)
+    # Assign hashed_password = Column(String, nullable=False)
     hashed_password = Column(String, nullable=False)
+    # Assign role = Column(String, nullable=False, default="viewer")
     role = Column(String, nullable=False, default="viewer")
+    # Assign is_active = Column(Boolean, default=True)
     is_active = Column(Boolean, default=True)
+    # Assign must_change_password = Column(Boolean, default=True)
     must_change_password = Column(Boolean, default=True)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
     created_at = Column(DateTime(timezone=True), server_default=func.now())
+    # Assign last_login = Column(DateTime, nullable=True)
     last_login = Column(DateTime, nullable=True)