Document Retain and add test

Expand the doc comment to explain: in-place semantics vs NewBSIRetainSet,
why skipping bA when dropped==0 is correct (BSI consistency invariant), and
when to prefer Retain over the allocating alternative.

The in-place form is used in caterwaul's CleanBitmaps, which iterates every
term bitmap and filters it down to currently-valid doc IDs before writing it
back to storage. No new BSI allocation is needed since the result is
immediately serialized.