BE-PR-002: Proposal model naming & field adjustments

- Add comprehensive docstring to Proposal model documenting all relationships
- Add column comments for all fields (title, description, status, project_id, etc.)
- Mark feat_task_id as DEPRECATED (will be replaced by Essential->task mapping in BE-PR-008)
- Add proposal_code hybrid property as preferred alias for DB column propose_code
- Update ProposalResponse schema to include proposal_code alongside propose_code
- Update serializer to emit both proposal_code and propose_code for backward compat
- No DB migration needed -- only Python-level changes

app/models/proposal.py

@@ -1,4 +1,5 @@
 from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, Enum
+from sqlalchemy.ext.hybrid import hybrid_property
 from sqlalchemy.sql import func
 from app.core.config import Base
 import enum
@@ -11,23 +12,73 @@ class ProposalStatus(str, enum.Enum):
 
 
 class Proposal(Base):
+    """Proposal model — a suggested scope of work under a Project.
+
+    After BE-PR-001 rename: Python class is ``Proposal``, DB table stays ``proposes``
+    for backward compatibility.
+
+    Relationships
+    -------------
+    - ``project_id``    — FK to ``projects.id``; every Proposal belongs to exactly
+                          one Project.
+    - ``created_by_id`` — FK to ``users.id``; the user who authored the Proposal.
+                          Nullable for legacy rows created before tracking was added.
+    - ``feat_task_id``  — **DEPRECATED**.  Previously stored the single generated
+                          ``story/feature`` task id on accept.  Will be replaced by
+                          the Essential → story-task mapping (see BE-PR-008).
+                          Kept in the DB column for read-only backward compat; new
+                          code MUST NOT write to this field.
+    """
+
     __tablename__ = "proposes"  # keep DB table name for compat
 
     id = Column(Integer, primary_key=True, index=True)
-    propose_code = Column(String(64), nullable=True, unique=True, index=True)  # keep column name for DB compat
-    title = Column(String(255), nullable=False)
-    description = Column(Text, nullable=True)
-    status = Column(Enum(ProposalStatus, values_callable=lambda x: [e.value for e in x]), default=ProposalStatus.OPEN)
 
-    project_id = Column(Integer, ForeignKey("projects.id"), nullable=False)
-    created_by_id = Column(Integer, ForeignKey("users.id"), nullable=True)
+    # DB column stays ``propose_code`` for migration safety; use the
+    # ``proposal_code`` hybrid property in new Python code.
+    propose_code = Column(
+        String(64), nullable=True, unique=True, index=True,
+        comment="Unique human-readable code, e.g. PROJ:P00001",
+    )
 
-    # Populated server-side after accept; links to the generated feature story task
-    feat_task_id = Column(String(64), nullable=True)
+    title = Column(String(255), nullable=False, comment="Short title of the proposal")
+    description = Column(Text, nullable=True, comment="Detailed description / rationale")
+
+    status = Column(
+        Enum(ProposalStatus, values_callable=lambda x: [e.value for e in x]),
+        default=ProposalStatus.OPEN,
+        comment="Lifecycle status: open → accepted | rejected",
+    )
+
+    project_id = Column(
+        Integer, ForeignKey("projects.id"), nullable=False,
+        comment="Owning project",
+    )
+    created_by_id = Column(
+        Integer, ForeignKey("users.id"), nullable=True,
+        comment="Author of the proposal (nullable for legacy rows)",
+    )
+
+    # DEPRECATED — see class docstring.  Read-only; will be removed once
+    # Essential-based accept (BE-PR-007 / BE-PR-008) is fully rolled out.
+    feat_task_id = Column(
+        String(64), nullable=True,
+        comment="DEPRECATED: id of the single story/feature task generated on old-style accept",
+    )
 
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     updated_at = Column(DateTime(timezone=True), onupdate=func.now())
 
+    # ---- convenience alias ------------------------------------------------
+    @hybrid_property
+    def proposal_code(self) -> str | None:
+        """Preferred accessor — maps to the DB column ``propose_code``."""
+        return self.propose_code
+
+    @proposal_code.setter  # type: ignore[no-redef]
+    def proposal_code(self, value: str | None) -> None:
+        self.propose_code = value
+
 
 # Backward-compatible aliases
 ProposeStatus = ProposalStatus