thanks all! so digging into the iReal Pro docs leads to these chords being called (as mentioned above) 'alternate chords', but doesn't give any indication of when they should be played, just how to notate them in iReal Pro charts
then googling around variations on 'when to use alternate chords on a jazz chart' only leads to either altered chords or chord substitutions, neither of which is what we're looking for here.
advice from this thread (again thanks) can be distilled down to "it depends", which is pretty much what I've discovered is the general guideline for most questions arising from trying to get hip to learning jazz!