promote residual momentum ranking

app/models/benchmark_price.py

@@ -10,8 +10,8 @@ class BenchmarkPrice(Base):
     """Daily close for a benchmark index (e.g. SPY), used to compute trade alpha.
 
     A standalone price series, deliberately NOT a tracked ``Ticker`` — so the
-    benchmark never enters the scanner, the momentum-percentile ranking, or the
-    rankings table. One row per (symbol, date).
+    benchmark never becomes a trade candidate or rankings-table row. Its closes
+    are used for residual momentum and trade alpha. One row per (symbol, date).
     """
 
     __tablename__ = "benchmark_prices"

app/models/trade_setup.py

@@ -26,8 +26,9 @@ class TradeSetup(Base):
     )
 
     confidence_score: Mapped[float | None] = mapped_column(Float, nullable=True)
-    # Ticker's 12-1 momentum percentile across the universe at detection time
-    # (0–100, 100 = strongest). Drives the activation gate's core selection.
+    # Ticker's activation momentum percentile across the universe at detection
+    # time. Since July 2026 this is residual 12-1 momentum when benchmark data is
+    # available, with raw 12-1 as a fallback.
     momentum_percentile: Mapped[float | None] = mapped_column(Float, nullable=True)
     targets_json: Mapped[str | None] = mapped_column(Text, nullable=True)
     conflict_flags_json: Mapped[str | None] = mapped_column(Text, nullable=True)