docs: improve KUHF/KROHF nelec error to mention nkpts scaling for cell.spin (#3321) - #3355

Problem

KUHF.nelec and KROHF.nelec raise a RuntimeError with an unhelpful message when
an open-shell k-point calculation is attempted with cell.spin set to the physical
per-cell spin rather than cell.spin * nkpts.

The current error reads:

RuntimeError: Electron number 264 and spin 1 are not consistent
Note cell.spin = 2S = Nalpha - Nbeta, not 2S+1

This does not explain why there is a mismatch, leaving users confused about the
k-point scaling requirement.

Root cause

KUHF.nelec computes total electrons as ne = cell.tot_electrons(nkpts) — which
scales by nkpts — but then does:

nalpha = (ne + cell.spin) // 2  # cell.spin is per-cell, ne is total

For consistency, cell.spin must equal (Nalpha - Nbeta per cell) * nkpts when
using k-point sampling with nkpts > 1. Gamma-point (single k-point) calculations
are unaffected since the scaling factor is 1.

Fix

Improve the error message to explicitly state the k-points scaling requirement:

RuntimeError: Electron number 264 and spin 1 are not consistent
Note cell.spin = 2S = Nalpha - Nbeta, not 2S+1.
For k-point calculations (nkpts=8), cell.spin must be the per-cell spin
multiplied by nkpts: cell.spin = (Nalpha - Nbeta per cell) * nkpts

This makes the path to resolution immediately clear.

Closes #3321.